home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / source / emacs-18.59src.lha / emacs-18.59 / amiga / contrib / lindgren / sas-c-emacs.lha / sas-c.doc < prev    next >
Encoding:
Text File  |  1993-06-10  |  10.1 KB  |  339 lines
  1.                    
  2.                   sas-c-mode
  3.                   ~~~~~~~~~~
  4.  
  5.                  V0.2  Beta 2
  6.  
  7.         Copyright (C) 1993 by Anders Lindgren.
  8.                    
  9.  
  10. Note: This is a BETA, that means that it hasn't undergone thoroughly
  11. testing, all possibel commands hasn't been written.
  12.  
  13. Suggestions and bugreports are highly appreciated.
  14.  
  15.                    
  16.                  DISTRIBUTION
  17.  
  18.     sas-c-mode is free software; you can redistribute it and/or modify
  19.     it under the terms of the GNU General Public License as published 
  20.     by the Free Software Foundation; either version 1, or (at your 
  21.     option) any later version.
  22.  
  23.     GNU Emacs is distributed in the hope that it will be useful,
  24.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  25.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26.     GNU General Public License for more details.
  27.  
  28.     You should have received a copy of the GNU General Public
  29.     License along with GNU Emacs; see the file COPYING.  If not,
  30.     write to the Free Software Foundation, 675 Mass Ave, Cambridge,
  31.     MA 02139, USA.
  32.  
  33.  
  34.     SAS and SAS/C are registrated trademarks of SAS Institute Inc.
  35.  
  36.                    
  37.                  INTRODUCTION
  38.  
  39. This package is the glue that ties the SAS/C message handler, SCMSG,
  40. to GNUEmacs for automatic error message reporting.
  41.  
  42. sas-c-mode is in GNU Emacs terms a minor mode. This means that it is
  43. an addition to the current major mode, such as c-mode. When enabled
  44. the text "SAS/C" will be present to the right of the the name of the
  45. current mode. The sas-c-mode rebinds keys of the current local keymap,
  46. when it is terminated the original definitions are restored.
  47.  
  48. The idea to make sas-c-mode a minor, as opposed to major, mode is to
  49. be able to use the features of c-mode. It can also be enabled when
  50. editing smakefiles or assmebler files.
  51.  
  52. Files contained in this package:
  53.  
  54. sas-c.doc        This file.
  55. sas-c.el        Source code in elisp.
  56. sas-c.elc        Byte-compiled version of the above.
  57. SCMSG.opt.SC_EMACS    Options for SCMSG.
  58. sc_emacs.rexx        Handler for SCMSG->Emacs communication.
  59. quithost.rexx        Terminates sc_emacs.
  60. slashquote/
  61.   slashquote.library    A ARexx host library containing two functions.
  62.   slashquote.doc    A small docfile for the above.
  63.   slashquote.c        The sourcecode.
  64.   slashquote.fd        Library description file, used by slink to build
  65.             the library.
  66.   smakefile        file containing rules for building 
  67.             slashquote.library
  68.   
  69. Note: All but the first four files will probable not be contained in
  70. future releases. They are only needed as workarounds for bugs and
  71. bad design of SCMSG, which hopefully will be fixed in 6.3. Until then
  72. I will consider this program BETA.
  73.  
  74.  
  75.                    INSTALL
  76.  
  77. * The library "slashquote.library" must be placed in LIBS:
  78.  
  79. * Place the file sas-c-mode.elc into a lisp directory (for example
  80.   GNUEmacs:lisp)
  81.  
  82. * Move sc_emacs.rexx and quithost.rexx to your rexx: directory.
  83.  
  84. * Turn on the ErrorRexx option in SCOPTS.
  85.  
  86. * Copy SCMSG.opt.SC_EMACS to ENV:sc/SCMSG and ENVARC:sc/SCMSG.
  87.  
  88. * The following line should be placed in s:.emacs
  89.  
  90.     (autoload 'sas-c-mode "sas-c" nil t)
  91.  
  92.  
  93. * If you would like the sas-c-minor mode to be activated automagically
  94.   when editing C-files, place the following lines into your s:.emacs
  95.  
  96.     (setq c-mode-hook '(lambda ()
  97.                  ;;; Other thing to do when entering 
  98.                  ;;; c-mode goes here.
  99.                  (sas-c-mode 1))
  100.  
  101.     
  102. If you know how to give the command "evaluate-region" on the lines
  103. entered into s:.emacs, do it. Otherwise quit and restart emacs.
  104.  
  105.  
  106.                  REQUIREMENTS
  107.  
  108. Atleast SAS/C 6.0 and Emacs V1.28 is required for this program. Please
  109. use sas-c-mode-B1.lha for Emacs V1.26.
  110.  
  111.  
  112.                    EXAMPLE
  113.  
  114. A normal sequence of events is the following:
  115.  
  116. * You compile a program, and an error occur. If no error occured, 
  117.   something must be very unnormal :-)
  118. * The SCMSG is started by the compiler, if it's option RexxOnly
  119.   is activated, no window is opened.
  120. * Automatically (if AUTOEDIT is enabled), or when an error is
  121.   doubleclicked, the SC_EMACS host is started.
  122. * Emacs is started, if it isn't already running.
  123. * The cursor is placed on the correct line in the correct file
  124.   and the current errormessage is displayed in the minibuffer.
  125. * The message will disappear if the cursor is moved; press
  126.   C-c C-l to rediplay it.
  127. * Press C-c C-n to see next error, or C-c C-d to delete the current and
  128.   see next.
  129. * When done, press C-c C-c to rebuild the project.
  130.  
  131.  
  132.                 USAGE
  133.  
  134. The following keys are defined by default when sas-c-mode is
  135. active:
  136.  
  137. C-c C-a        Display the alternative file, if any.
  138. C-c C-c        Build a project (normally execute smake).
  139. C-c C-d        Delete the current message and display next.
  140. C-c C-h        Hide the SCMSG window.
  141. C-c C-l        Redisplay current error message.
  142. C-c C-n        Display next error message.
  143. C-c <down>        ---- " ----
  144. C-c C-p        Display previous error message.
  145. C-c <up>        ---- " ----
  146. C-c C-q        Remove all messages for a certain primary file.
  147. C-c C-s        Show the SCMSG window.
  148. C-c <        Go to the first error message.
  149. C-c <sh. up>        ---- " ----
  150. C-c >        Go to the last error message.
  151. C-c <sh. down>        ---- " ----
  152.  
  153. When an error is displayed, the mark is set at the previous cursor
  154. position. Press C-x C-x to return to the old position.
  155.  
  156.  
  157. The message is displayed in the following forms:
  158.  
  159.     Class #: text
  160.  
  161. Where Class is "Error", "Warning" or "Info". # is the error number and
  162. text is the actual message. If there exists an alternate file the string
  163. "(Alt)" is placed immediately to the left of the colon. To see it, press
  164. C-c C-a. The primary file can always be reviewed by pressing C-c C-l.
  165.  
  166.  
  167.                   VARIABLES
  168.  
  169. sas-c-mode    non-nil if in sas-c minor mode. READ ONLY.
  170.  
  171. sas-c-compile-command
  172.         Command to use when building project (default "sc:c/smake").
  173.  
  174.  
  175.                   FUNCTIONS
  176.  
  177. sas-c-bottom    Go to the last message.
  178.  
  179. sas-c-build    Rebuild the current project. This is done by executing
  180.         the command in the variable sas-c-compile-command
  181.         (default sc:c/smake.)
  182.         
  183. sas-c-delete    Delete the current error message and move to the next.
  184.  
  185. sas-c-delcomp-current    
  186.         Delete all messages with the same primary filename
  187.         as the current error. NOTE: This function does not take
  188.         the filename from the current buffer.
  189.         Also note: This function is not bound to a key since
  190.         I belive it's a little bit unintuitive.
  191.  
  192. sas-c-delcomp    Prompt for a for a filename to remove from the error list.
  193.         Default is current buffer.
  194.  
  195. sas-c-delfile-current    
  196.         Same as sas-c-delcomp-current, but for secondary file.
  197.         NOTE: This function is not currently impelemented,
  198.         since SCMSG crashes when it is executed.
  199.  
  200. sas-c-delfile    Same as sas-c-delcomp, but for secondary filename.
  201.  
  202. sas-c-display-altfile
  203.         This function displays the alternate file and places
  204.         the cursor on the corrent line.
  205.  
  206. sas-c-display-error
  207.         This function displays the current error and places the
  208.         cursor on the offending line.
  209.  
  210. sas-c-hide    Close the SCMSG window.
  211.  
  212. sas-c-next    Move to the next error message. (If at the last message,
  213.         go to the top.)
  214.  
  215. sas-c-prev    move to the previous error message. (If at the top, go
  216.         to the bottom.)
  217.  
  218. sas-c-show    Show the SCMSG window. If called with an argument
  219.         the window gets unactivated. (i.e. call if called
  220.         with C-u M-x sas-c-show RET.)
  221.  
  222. sas-c-top    Go to the top of error messages.
  223.  
  224.  
  225.                 CUSTOMIZATION
  226.  
  227. The sac-c-mode can be custimized. a special variable sas-c-mode-hook
  228. is defined for this purpose. It shall be defined as below:
  229.  
  230. (setq sas-c-mode-hook 
  231.       (function (lambda ()
  232.           ;;; Things to do here
  233.           )))
  234.  
  235. When defining new keys the function sas-c-define-key must be used. If
  236. not, the mechanism which removes the keybindings when sas-c-mode is
  237. terminated won't work.
  238.  
  239. For example:
  240.  
  241. (setq sas-c-mode-hook 
  242.       (function (lambda ()
  243.           (sas-c-define-key "\C-x`" 'sas-c-next)
  244.           (sas-c-define-key "\C-c\C-q" 'sas-c-delcomp-current))))
  245.  
  246. This defines C-x ` as sas-c-next. This is quite useful for people
  247. who are used to the old "compile" macro. It also redefines the
  248. key C-c C-q to use sas-c-delcomp-current, instead of sas-c-delcomp.
  249.  
  250.  
  251.                  TIPS n'TRIX
  252.  
  253. If you are going to compile from within emacs, I recomend using
  254. the NOERRORHIGHLIGHT and BATCH flags.
  255.  
  256. It is useful to be able to compile (C-c C-c) from a makefile. I normally
  257. places the following lines into the header of the makefile to make it
  258. use the sas-c minor mode:
  259. (According to Emacs rules the local variables should be placed on
  260. the last page of the file.)
  261.  
  262. #       Local Variables:
  263. #       eval:(sas-c-mode 1)
  264. #       End:
  265.  
  266.  
  267.                 HOW TO EXPAND
  268.  
  269. sas-c-mode can be expanded with new clever commands, just start up
  270. your brain!
  271.  
  272. The following ELisp functions can be useful:
  273.  
  274. (sas-c-view-message file line text class errnum)
  275.     Display the actual error message. It reads in the file, if
  276.     it's not in any buffer. It then shows the buffer and places
  277.     the cursor on the correct line and displays the errortext.
  278.  
  279. (sas-c-get-file file)
  280.     Used by above.
  281.  
  282. (sas-c-scmsg command)
  283.     Send a ARexx command to SCMSG without requesting a resultstring.
  284.  
  285. (sas-c-scmsg-str command)
  286.     Send a ARexx command to SCMSG and return the resultstring.
  287.  
  288. (sas-c-scmsg-str command)
  289.     Send a ARexx command to SCMSG and return a number.
  290.  
  291.  
  292.                 KNOWN PROBLEMS
  293.  
  294. SCMSG has given me quite a headache during the development due to a
  295. unfoutnate combination of bad design and bugs. The main problem is
  296. that the mechanism which calls the editor can't be used directly since
  297. it often emits strings with quotes, resulting in syntactically
  298. incorrect ELisp statements. It also only quotes filenames containing
  299. spaces resulting in inconsistency when writing a template of the form:
  300.  
  301.     (sas-c-get-file "%f")
  302.  
  303. which is expanded into:
  304.  
  305.     (sas-c-get-file ""foo bar.c"")
  306.  
  307. which also is an incorrent ELisp statement.
  308.  
  309. My idea to fix SCMSG is 1) never (or always) puts quotes around
  310. strings. 2) add an extra option ESCAPECHAR, a characher which is
  311. placed before all quotes (and itself) in the %f and %m strings.
  312. (default is, of cource, NOESCAPECHAR, for the sake of backward
  313. compability). (I hold my thumbs, SAS).
  314.  
  315. SCMSG crashes when the ARexx command 'delfile' is given.
  316.  
  317.  
  318.                  FINAL WORDS
  319.  
  320. A special thank is given to Malin, who has put up with me while
  321. writing this, and other programs.
  322.  
  323. I would also thank Swedish User Group of Amiga, SUGA, for their
  324. immense support!
  325.  
  326. Suggestions, new ideas and (positive) criticism are highly
  327. appreciated. Please email them to:
  328.  
  329.         d91ali@csd.uu.se
  330.  
  331.     or snail mail them to:
  332.  
  333.         Anders Lindgren
  334.         Kantorsg. 2-331
  335.         754 24 Uppsala
  336.         Sverige
  337.  
  338.                     /Anders Lindgren, 93-06-09
  339.